USB Transaction Functions
There are four transaction types supported by the USL, control, interrupt, bulk, or isochronous. When making isochronous calls, you set the
pbVersion
field in the
USBPB
parameter block to
kUSBIsocPBVersion, and use the isochronous variant of the
USBPB
parameter block, described in
The Isochronous Version Of The USBPB
.
USBIntRead
The
USBIntRead
function queues an interrupt transaction on the specified pipe. The device is periodically polled and the transaction completes when the device returns some data. This is a read operation only. Version 1.0 of the USB specification does not define an interrupt write function.
OSStatus USBIntRead(USBPB *pb);
Required fields in the
USBPB
parameter block for the USBIntRead function are
-
--> pbLength
-
Length of parameter block
-
--> pbVersion
-
Parameter block version number
-
--> usbCompletion
-
The completion routine
-
--> usbRefcon
-
General-purpose value passed back to the completion routine
-
--> usbReference
-
The pipe reference returned by the
USBFindNextPipe
function
-
--> usbReqCount
-
Specifies the size of the data to transfer. If this is set to 0, anything but a zero length packet causes an error
-
--> usbBuffer
-
Points to a buffer to which the incoming data is transferred
-
<-- usbActCount
-
Specifies the actual amount of data transferred on completion
-
--> usbFlags
-
Should be set to 0
In order to avoid the loss of data when transferring data from a device,
usbBuffer
and
usbReqCount
should be a multiple of the value of the
MaxPacketSize
field, in the device's endpoint descriptor.
Errors returned by the
USBIntRead
function include
kUSBUnknownPipeErr
|
-6997
|
pipe reference specified is unknown
|
kUSBIncorrectTypeErr
|
-6995
|
pipe is not an interrupt pipes
|
kUSBPipeIdleErr
|
-6980
|
specified pipe is in the idle state
|
kUSBPipeStalledErr
|
-6979
|
specified pipe is stalled
|
USBBulkRead
The
USBBulkRead
function can be used to request multiple bulk transactions on an inbound bulk pipe to fulfill the size of request specified, or for the entire transfer.
OSStatus USBBulkRead(USBPB *pb);
Required fields in the
USBPB
parameter block for the USBBulkRead function are
-
--> pbLength
-
Length of parameter block
-
--> pbVersion
-
Parameter block version number
-
--> usbCompletion
-
The completion routine
-
--> usbRefcon
-
General-purpose value passed back to the completion routine
-
--> usbReference
-
The pipe reference returned by the USBFindNextPipe function
-
--> usbReqCount
-
Specifies the size of the data to transfer. Must be a multiple of the packet size. If it is not a multiple of the packet size, the last packet my overrun. If set to 0, any non-zero size transfer causes an error
-
--> usbBuffer
-
Points to a buffer to which the incoming data is transferred
-
<-- usbActCount
-
Specifies the actual amount of data transferred on completion
-
--> usbFlags
-
Should be set to 0
In order to avoid the loss of data when transferring data from a device,
usbBuffer
and
usbReqCount
should be a multiple of the endpoint
MaxPacketSize
in the device's endpoint descriptor.
Errors returned by the
USBBulkRead
function include
kUSBUnknownPipeErr
|
-6997
|
pipe reference specified is unknown
|
kUSBIncorrectTypeErr
|
-6995
|
pipe reference is not a bulk-in pipe
|
kUSBPipeIdleErr
|
-6980
|
specified pipe is in the idle state
|
kUSBPipeStalledErr
|
-6979
|
specified pipe is stalled
|
USBBulkWrite
The
USBBulkWrite
function requests multiple bulk out transactions on an outbound bulk pipe to fulfill the size of request specified.
OSStatus USBBulkWrite(USBPB *pb);
Required fields in the
USBPB
parameter block for the USBBulkWrite function are
-
--> pbLength
-
Length of parameter block
-
--> pbVersion
-
Parameter block version number
-
--> usbCompletion
-
The completion routine
-
--> usbRefcon
-
General-purpose value passed back to the completion routine
-
--> usbReference
-
The pipe reference returned by the
USBFindNextPipe
or
USBOpenPipe
functions
-
--> usbReqCount
-
Specifies the size of the data to transfer. If this is set to 0, no data transfer occurs, but the device senses a 0 length bulk transaction
-
--> usbBuffer
-
Points to the data to be transferred. The buffer should be at least as big as the size specified in the
usbReqCount
field. If the buffer is set to
nil, no data is transferred regardless of the value of
usbReqCount
-
<-- usbActCount
-
Specifies the actual amount of data transferred on completion
-
--> usbFlags
-
Should be set to 0
-
Errors returned by the
USBBulkWrite
function include
-
kUSBUnknownPipeErr
|
-6997
|
pipe reference specified is unknown
|
kUSBIncorrectTypeErr
|
-6995
|
pipe reference is not a bulk-out pipe
|
kUSBPipeIdleErr
|
-6980
|
specified pipe is in the idle state
|
kUSBPipeStalledErr
|
-6979
|
specified pipe is stalled
|
USBIsocRead
The
USBIsocRead
function is defined as follows:
OSStatus USBIsocRead(USBIsocPB *pb);
Required fields in the isochronous version of the
USBPB
parameter block for the USBIsocRead function are
-
--> pbLength
-
Length of parameter block
-
--> pbVersion
-
Parameter block version, must be
kUSBIsocPBVersion
for isochronous function calls
-
<--usbStatus
-
Aggregate status, see discussion in
The Isochronous Version Of The USBPB
-
--> usbCompletion
-
The completion routine
-
--> usbRefcon
-
General-purpose value passed back to the completion routine
-
--> usbReference
-
The isochronous pipe reference returned by the
USBFindNextPipe
function
-
--> usbReqCount
-
Specifies the size of the data to transfer. May be any size, but no less than the sum of the individual packets sizes. If set to 0, any non-zero size transfer causes an error.
-
--> usbBuffer
-
Points to a buffer to which the incoming data is transferred
-
<-- usbActCount
-
Specifies the actual amount of data transferred on completion
-
--> usbFlags
-
Should be set to 0
-
--> usb.isoc.FrameList
-
Pointer to the list of frame structures
--> frReqCount
Number of bytes requested for each packet
<-- frStatus
Status returned by packet
<-- frActCount
Actual bytes transferred by packet
-
--> usb.isoc.NumFrames
-
Number of frames to attempt transfers in
-
--> usbFrame
-
Frame number of the first frame to transfer data
USBIsocWrite
The
USBIsocWrite
function is defined asfollows:
USBIsocWrite(USBIsocPB *pb);
Required fields in the isochronous version of the
USBPB
parameter block for the USBIsocWrite function are
-
--> pbLength
-
Length of parameter block
-
--> pbVersion
-
Parameter block version, must be
kUSBIsocPBVersion
for isochronous function calls
-
<--usbStatus
-
Aggregate status, see discussion in
The Isochronous Version Of The USBPB
-
--> usbCompletion
-
The completion routine
-
--> usbRefcon
-
General-purpose value passed back to the completion routine
-
--> usbReference
-
The isochronous pipe reference returned by the
USBFindNextPipe
or
USBOpenPipe
functions
-
--> usbReqCount
-
Specifies the size of the data to transfer. If this is set to 0 in the frReqCount field in the frame structure, the call sends a packet size of 0.
-
--> usbBuffer
-
Points to the data to be transferred. The buffer should be at least as big as the size specified in the
usbReqCount
field. If the buffer is set to
nil, no data is transferred regardless of the value of
usbReqCount
-
<-- usbActCount
-
Specifies the actual amount of data transferred on completion
-
--> usbFlags
-
Should be set to 0
-
--> usb.isoc.FrameList
-
Pointer to the list of frame structures
--> frReqCount
Number of bytes requested for each packet
<-- frStatus
Status returned by packet
<-- frActCount
Actual bytes transferred by packet
-
--> usb.isoc.NumFrames
-
Number of frames to attempt transfers in
-
--> usbFrame
-
Frame number of the first frame to transfer data
© 1998 Apple Computer, Inc. – (Last Updated 23 Nov 98)Previous | Back Up One Level | Next |